--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
README.md 559f6bc8f25bbb9ee5b81bcd4e39939f8a24b374 (559f6bc8) Text, 11.66 KB
Tc9d1d9# Reticulum MeshChatX
[Tff7b72Русский](Te6edf3lang/README.ru.md) | [Tff7b72Deutsch](Te6edf3lang/README.de.md) | [Tff7b72Italiano](Te6edf3lang/README.it.md) | [Tff7b72中文](Te6edf3lang/README.zh.md) | [Tff7b72日本語](Te6edf3lang/README.ja.md)
A extensively modified and feature-rich fork of Reticulum MeshChat by Liam Cottle.
This project is independent from the original Reticulum MeshChat project and is not affiliated with it.
Tff7b72- Website: [Tff7b72meshchatx.com](Te6edf3https://meshchatx.com)
Tff7b72- Source: [Tff7b72git.quad4.io/RNS-Things/MeshChatX](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX)
Tff7b72- Official Mirror: [Tff7b72github.com/Sudo-Ivan/MeshChatX](Te6edf3https://github.com/Sudo-Ivan/MeshChatX) - Also used for Windows and MacOS builds for the moment.
Tff7b72- Releases: [Tff7b72git.quad4.io/RNS-Things/MeshChatX/releases](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX/releases)
Tff7b72- Changelog: [Ta5d6ff`CHANGELOG.md`](CHANGELOG.md)
Tff7b72- TODO: [Tff7b72Boards](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX/projects)
Tc9d1d9## Important Changes from Reticulum MeshChat
Tff7b72- Uses LXST
Tff7b72- Replaced Peewee ORM with raw SQL.
Tff7b72- Replaced Axios with native fetch.
Tff7b72- Uses latest Electron.
Tff7b72- .whls ships with webserver and built-in frontend assets for more deployment options.
Tff7b72- i18n
Tff7b72- PNPM and Poetry for dependency management.
Tff7b72> [!WARNING]
Tff7b72> MeshChatX is not guaranteed to be wire/data compatible with older Reticulum MeshChat releases. Back up data before migration/testing.
Tff7b72> [!WARNING]
Tff7b72> Legacy systems are not fully supported yet. Current baseline is Python `>=3.11` and Node `>=24`.
Tc9d1d9## Requirements
Tff7b72- Python Ta5d6ff`>=3.11` (from Ta5d6ff`pyproject.toml`)
Tff7b72- Node.js Ta5d6ff`>=24` (from Ta5d6ff`package.json`)
Tff7b72- pnpm Ta5d6ff`10.32.1` (from Ta5d6ff`package.json`)
Tff7b72- Poetry (used by Ta5d6ff`Taskfile.yml` and CI workflows)
Ta5d6ff```Ta5d6ffbash
task install
task lint:all
task test:all
task build:all
Ta5d6ff```
Tc9d1d9## Install Methods
Use the method that matches your environment and packaging preference.
| Method | Includes frontend assets | Architectures | Best for |
| ----------------------- | ------------------------ | ------------------------------------------ | ---------------------------------------------- |
| Docker image | Yes | Ta5d6ff`linux/amd64`, Ta5d6ff`linux/arm64` | Fastest setup on Linux servers/hosts |
| Python wheel (Ta5d6ff`.whl`) | Yes | Any Python-supported architecture | Headless/web-server install without Node build |
| Linux AppImage | Yes | Ta5d6ff`x64`, Ta5d6ff`arm64` | Portable desktop use |
| Debian package (Ta5d6ff`.deb`) | Yes | Ta5d6ff`x64`, Ta5d6ff`arm64` | Debian/Ubuntu installs |
| RPM package (Ta5d6ff`.rpm`) | Yes | CI-runner dependent for published artifact | Fedora/RHEL/openSUSE style systems |
| From source | Built locally | Host architecture | Development and custom builds |
Notes:
Tff7b72- The release workflow explicitly builds Linux Ta5d6ff`x64` and Ta5d6ff`arm64` AppImage + DEB.
Tff7b72- RPM is also attempted by release workflow and uploaded when produced.
Tc9d1d9## Quick Start: Docker
Ta5d6ff```Ta5d6ffbash
docker compose up -d
Ta5d6ff```
Default compose file maps:
Tff7b72- Ta5d6ff`127.0.0.1:8000` on host -> container port Ta5d6ff`8000`
Tff7b72- Ta5d6ff`./meshchat-config` -> Ta5d6ff`/config` for persistence
If your local Ta5d6ff`meshchat-config` permissions block writes, fix ownership:
Ta5d6ff```Ta5d6ffbash
sudo chown -R T79c0ff1000:1000 ./meshchat-config
Ta5d6ff```
Tc9d1d9## Install from Release Artifacts
Tc9d1d9### 1) Linux AppImage (x64/arm64)
Tff7b721. Download Ta5d6ff`ReticulumMeshChatX-v<version>-linux-<arch>.AppImage` from releases.
Tff7b722. Make it executable and run:
Ta5d6ff```Ta5d6ffbash
chmod +x ./ReticulumMeshChatX-v*-linux-*.AppImage
./ReticulumMeshChatX-v*-linux-*.AppImage
Ta5d6ff```
Tc9d1d9### 2) Debian/Ubuntu `.deb` (x64/arm64)
Tff7b721. Download Ta5d6ff`ReticulumMeshChatX-v<version>-linux-<arch>.deb`.
Tff7b722. Install:
Ta5d6ff```Ta5d6ffbash
sudo apt install ./ReticulumMeshChatX-v*-linux-*.deb
Ta5d6ff```
Tc9d1d9### 3) RPM-based systems
Tff7b721. Download Ta5d6ff`ReticulumMeshChatX-v<version>-linux-<arch>.rpm` if present in the release.
Tff7b722. Install with your distro tool:
Ta5d6ff```Ta5d6ffbash
sudo rpm -Uvh ./ReticulumMeshChatX-v*-linux-*.rpm
Ta5d6ff```
Tc9d1d9### 4) Python wheel (`.whl`)
Release wheels include the built web assets.
Ta5d6ff```Ta5d6ffbash
pip install ./reticulum_meshchatx-*-py3-none-any.whl
meshchatx --headless
Ta5d6ff```
Ta5d6ff`pipx` is also supported:
Ta5d6ff```Ta5d6ffbash
pipx install ./reticulum_meshchatx-*-py3-none-any.whl
Ta5d6ff```
Tc9d1d9## Run from Source (Web Server Mode)
Use this when developing or when you need a local custom build.
Ta5d6ff```Ta5d6ffbash
git clone https://git.quad4.io/RNS-Things/MeshChatX.git
Tffa657cd MeshChatX
corepack Tffa657enable
pnpm install
pip install poetry
poetry install
pnpm run build-frontend
poetry run python -m meshchatx.meshchat --headless --host T79c0ff127.0.0.1
Ta5d6ff```
Tc9d1d9## Run sandboxed (Linux)
To run the native Ta5d6ff`meshchatx` binary (alias: Ta5d6ff`meshchat`) with extra filesystem isolation, you can use **Firejail** or **Bubblewrap** (Ta5d6ff`bwrap`) while keeping normal network access for Reticulum and the web UI. Full examples (pip/pipx, Poetry, USB serial notes) are in:
Tff7b72- [Ta5d6ff`docs/meshchatx_linux_sandbox.md`](docs/meshchatx_linux_sandbox.md)
The same page appears in the in-app **Documentation** list (MeshChatX docs) when served from the bundled or synced Ta5d6ff`meshchatx-docs` files.
Tc9d1d9## Build Desktop Packages from Source
These scripts are defined in Ta5d6ff`package.json` and Ta5d6ff`Taskfile.yml`.
Tc9d1d9### Linux x64 AppImage + DEB
Ta5d6ff```Ta5d6ffbash
pnpm run dist:linux-x64
Ta5d6ff```
Tc9d1d9### Linux arm64 AppImage + DEB
Ta5d6ff```Ta5d6ffbash
pnpm run dist:linux-arm64
Ta5d6ff```
Tc9d1d9### RPM
Ta5d6ff```Ta5d6ffbash
pnpm run dist:rpm
Ta5d6ff```
Or through Task:
Ta5d6ff```Ta5d6ffbash
task dist:fe:rpm
Ta5d6ff```
Tc9d1d9## Architecture Support Summary
Tff7b72- Docker image: Ta5d6ff`amd64`, Ta5d6ff`arm64`
Tff7b72- Linux AppImage: Ta5d6ff`x64`, Ta5d6ff`arm64`
Tff7b72- Linux DEB: Ta5d6ff`x64`, Ta5d6ff`arm64`
Tff7b72- Windows: Ta5d6ff`x64`, Ta5d6ff`arm64` (build scripts available)
Tff7b72- macOS: build scripts available (Ta5d6ff`arm64`, Ta5d6ff`universal`) for local build environments
Tff7b72- Android: build workflow and Android project are present in this repository
Tc9d1d9## Android
Use the dedicated docs:
Tff7b72- [Ta5d6ff`docs/meshchatx_on_android_with_termux.md`](docs/meshchatx_on_android_with_termux.md)
Tff7b72- [Ta5d6ff`android/README.md`](android/README.md)
Tc9d1d9## Configuration
MeshChatX supports both CLI args and env vars.
| Argument | Environment Variable | Default | Description |
| -------------------------- | ---------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ta5d6ff`--host` | Ta5d6ff`MESHCHAT_HOST` | Ta5d6ff`127.0.0.1` | Web server bind address |
| Ta5d6ff`--port` | Ta5d6ff`MESHCHAT_PORT` | Ta5d6ff`8000` | Web server port |
| Ta5d6ff`--no-https` | Ta5d6ff`MESHCHAT_NO_HTTPS` | Ta5d6ff`false` | Disable HTTPS |
| Ta5d6ff`--ssl-cert` / Ta5d6ff`--ssl-key` | Ta5d6ff`MESHCHAT_SSL_CERT` / Ta5d6ff`MESHCHAT_SSL_KEY` | (none) | PEM certificate and private key paths; both must be set together. Overrides auto-generated certs under the identity Ta5d6ff`ssl/` directory. |
| Ta5d6ff`--rns-log-level` | Ta5d6ff`MESHCHAT_RNS_LOG_LEVEL` | (none) | Reticulum (RNS) stack log level: Ta5d6ff`none`, Ta5d6ff`critical`, Ta5d6ff`error`, Ta5d6ff`warning`, Ta5d6ff`notice`, Ta5d6ff`verbose`, Ta5d6ff`debug`, Ta5d6ff`extreme`, or a numeric level. CLI overrides env when both are set. |
| Ta5d6ff`--headless` | Ta5d6ff`MESHCHAT_HEADLESS` | Ta5d6ff`false` | Do not auto-launch browser |
| Ta5d6ff`--auth` | Ta5d6ff`MESHCHAT_AUTH` | Ta5d6ff`false` | Enable basic auth |
| Ta5d6ff`--storage-dir` | Ta5d6ff`MESHCHAT_STORAGE_DIR` | Ta5d6ff`./storage` | Data directory |
| Ta5d6ff`--public-dir` | Ta5d6ff`MESHCHAT_PUBLIC_DIR` | auto/bundled | Frontend files directory (needed for source installs without bundled assets) |
Tc9d1d9## Branches
| Branch | Purpose |
| -------- | --------------------------------------------------------------- |
| Ta5d6ff`master` | Stable releases. Production-ready code only. |
| Ta5d6ff`dev` | Active development. May contain breaking or incomplete changes. |
Tc9d1d9## Development
Common tasks from Ta5d6ff`Taskfile.yml`:
Ta5d6ff```Ta5d6ffbash
task install
task lint:all
task test:all
task build:all
Ta5d6ff```
Ta5d6ff`Makefile` shortcuts are also available:
| Command | Description |
| -------------- | --------------------------------------- |
| Ta5d6ff`make install` | Install pnpm and poetry dependencies |
| Ta5d6ff`make run` | Run MeshChatX via poetry |
| Ta5d6ff`make build` | Build frontend |
| Ta5d6ff`make lint` | Run eslint and ruff |
| Ta5d6ff`make test` | Run frontend and backend tests |
| Ta5d6ff`make clean` | Remove build artifacts and node_modules |
Tc9d1d9## Versioning
Current version in this repo is Ta5d6ff`4.4.0`.
Tff7b72- Ta5d6ff`package.json` is the JavaScript/Electron version source.
Tff7b72- Ta5d6ff`meshchatx/src/version.py` is synced from Ta5d6ff`package.json` using:
Ta5d6ff```Ta5d6ffbash
pnpm run version:sync
Ta5d6ff```
For release consistency, keep version fields aligned where required (Ta5d6ff`package.json`, Ta5d6ff`pyproject.toml`, Ta5d6ff`meshchatx/__init__.py`).
Tc9d1d9## Security
Security and integrity details:
Tff7b72- [Ta5d6ff`SECURITY.md`](SECURITY.md)
Tff7b72- Built-in integrity checks and HTTPS/WSS defaults in app runtime
Tff7b72- CI scanning workflows in Ta5d6ff`.gitea/workflows/`
Tc9d1d9## Adding a Language
Locale discovery is automatic. To add a new language, create a single JSON file:
Tff7b721. Generate a blank template from Ta5d6ff`en.json`:
Ta5d6ff```Ta5d6ffbash
python scripts/generate_locale_template.py
Ta5d6ff```
This writes Ta5d6ff`locales.json` with every key set to an empty string.
Tff7b722. Rename it to your language code and move it into the locales directory:
Ta5d6ff```Ta5d6ffbash
mv locales.json meshchatx/src/frontend/locales/xx.json
Ta5d6ff```
Tff7b723. Set Ta5d6ff`_languageName` at the top of the file to the native name of the language (e.g. Ta5d6ff`"Espanol"`, Ta5d6ff`"Francais"`). This is displayed in the language selector.
Tff7b724. Translate all remaining values.
Tff7b725. Run Ta5d6ff`pnpm test -- tests/frontend/i18n.test.js --run` to verify key parity with Ta5d6ff`en.json`.
No other code changes are required. The app, language selector, and tests all discover locales from the Ta5d6ff`meshchatx/src/frontend/locales/` directory at build time.
Tc9d1d9## Credits
Tff7b72- [Tff7b72Liam Cottle](Te6edf3https://github.com/liamcottle) - Original Reticulum MeshChat
Tff7b72- [Tff7b72RFnexus](Te6edf3https://github.com/RFnexus) - micron parser JavaScript work
Tff7b72- [Tff7b72markqvist](Te6edf3https://github.com/markqvist) - Reticulum, LXMF, LXST
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────